Skip to main content

改进错误响应处理

您的 API 返回的错误会在两个关键点给用户带来不便：

  • 在 Zap 设置过程中，阻止他们启用和激活 Zap
  • 在 Zap 运行时，一旦 Zap 被开启，阻止其成功完成所有操作

当 Zap 运行时，在向您的 API 发送请求时遇到错误响应状态码时，会抛出异常并显示“已停止/出错”状态。这会在用户的 Zap 历史记录中显示一条错误消息，并根据他们的通知设置 通过电子邮件通知他们。

即使响应中包含的 message 详细说明了错误，如果请求中存在问题，用户绝不应收到成功/200 响应，因为这不会在 Zap 历史记录中显示为错误。

如果过去 7 天内 Zap 的运行中有 95% 被标记为“已停止/出错”状态，则 Zap 会自动关闭。Zap 不会再次运行，除非用户手动启用它，因此仅在真正需要修复的错误场景下才返回错误。

在平台 UI 的“监控”页面监控错误激增情况，作为用户在您的集成中遇到问题的早期指标。

如果您的 API 和集成具备更具描述性和详尽的错误处理，用户将更容易自行解决其问题，而 Zapier 的支持团队也能更轻松地协助调试。

如果您无法直接修改 API，请利用自定义错误处理来改进错误消息：

  • 对简短的错误信息进行扩展，使用用户友好的消息表达。
  • 在编写面向用户的错误消息时，请确保消息总长度不超过 250 个字符，因为 Zapier 在向用户显示集成错误时会截断超过 250 个字符的部分。
  • 将“not_authenticated”更新为“Your API Key is invalid. Please reconnect your account.”（您的 API 密钥无效。请重新连接您的账户。）
  • 向用户提供关于特定字段及其出错原因的具体信息，从而使用户能够独立修复 Zap 问题。
  • 而不是返回“Provided data is invalid”（提供的数据无效），改为返回“Contact name is invalid”（联系人姓名无效）。
  • 改进“Contact name is invalid”为“Contact name exceeds character limit.”（联系人姓名超过字符限制）。
  • 将错误格式化为包括第二个可选参数（供机器用于识别错误类型）和最后一个可选参数（HTTP 状态码）。例如：throw new z.errors.Error('Contact name exceeds character limit.', 'InvalidData', 400);

您的应用集成可以通过自定义代码在 Zapier 中提升用户体验，返回用户友好的消息以及可选的错误代码和状态码。通常，这涉及到优化 4xx 响应或将错误作为 200 响应返回的 API，其中包含描述错误的负载。Zapier 会使用代码和状态码来为用户提供相关的故障排除建议。

先决条件​

1. Platform CLI 中的自定义错误​

切换到Platform CLI，允许您利用 HTTP 中间件来实现自定义错误响应处理。

这让您能够编写一个适用于整个集成的脚本，用于检测 API 的特定错误，并在 Zapier 中向用户显示相关消息。

2. Platform UI 中的自定义错误​

如果您在 UI 中构建和维护您的应用，仍然可以实现自定义错误处理。主要区别在于，您需要为集成中可能遇到错误的每个单独元素（触发器、操作、搜索、身份验证）添加处理。

在 UI 中，您可以通过高级选项卡设置 skipThrowForStatus，从而为 400 及以上的状态码实现自定义错误处理。请注意，401 状态码无论如何都会抛出 RefreshAuthError相关内容。

Platform UI vs CLI comparison

设置后，您可以在每个触发器/操作/搜索的 API 配置中的代码模式下添加错误处理。

return z.request(options).then((response) => {
  if (response.status === 404) {
    throw new z.errors.Error(
      "An error was returned. Help!",
      "InvalidData",
      404
    );
  }
  return response.json;
});

Platform UI vs CLI comparison